# Debian tutorial

This document is intended for beginners using the **Quectel Pi M1/L1 smart single-board computer** and is designed to help them quickly learn common Debian operations and development tasks. It covers file attributes and permissions, file management, text editing, and package management, making it suitable for users with no prior experience and those new to Linux.

# File attributes and permissions

Learn about Linux file types, ownership, and permission bits. Use **ls -l** to view file attributes, and use **chown** and **chmod** to manage ownership and access permissions.

In Linux, files have attributes such as the filename, size, owner, group, access permissions, type, and modification time. Understanding these attributes helps you determine why a script cannot be executed, a directory is not writable, or sudo is required to modify a system configuration file.

## How to view file attributes

The most common way to view file attributes is as follows:

```plaintext
ls -l
```

To also display hidden files and show file sizes in a more readable way, run the following command:

```plaintext
ls -lah
```

A typical output is shown below:

```plaintext
-rwxr-xr-- 1 pi pi 2048 Jun 22 10:30 demo.sh
```

This information can be split into the following parts:

| **Field** | **Example** | **Description** |
| --- | --- | --- |
| File type and permissions | -rwxr-xr-- | The first character indicates the file type, and the remaining nine characters indicate permissions. |
| Number of links | 1 | The number of directory entries pointing to the file. |
| Owner | pi | File owner. |
| Group | pi | The group that owns the file. |
| Size | 2048 | File size. Unit: bytes (default). |
| Modification time | Jun 22 10:30 | Last modification time. |
| File name | demo.sh | File name. |

## File type identification

The first character in the permission string indicates the file type:

For example:

- drwxr-xr-x: Directory.

- -rw-r--r--: Regular file.

- lrwxrwxrwx: Symbolic link.

## Permission bit structure description

The nine characters from positions 2 through 10 are divided into three groups:

```plaintext
rwx r-x r--
|   |   |
|   |   +-- Other users (others) permissions
|   +------ Group (group) permissions
+---------- Owner (owner) permissions
```

Each set of permissions contains the following characters:

| **Symbol** | **Meaning** |
| --- | --- |
| r | Readable |
| w | Writable |
| x | Executable |
| - | No permission |

For example:

- rw-r--r--: The owner can read and write the file, while the group and other users can only read it.

- rwxr-xr-x: The owner can read, write, and execute the file, while the group and other users can read and execute it.

### chown: manage owner and group

If a file is owned by the wrong user or group, use **chown** to change its ownership.

Basic syntax:

```plaintext
sudo chown [options] user[:group] file_or_directory
```

Common examples:

Change the file owner to pi:

```plaintext
sudo chown pi demo.sh
```

Change both the owner and group:

```plaintext
sudo chown pi:pi demo.sh
```

Recursively change the owner and group of the directory:

```plaintext
sudo chown -R pi:pi /home/pi/project
```

Change only the group:

```plaintext
sudo chown :pi /home/pi/project/config.json
```

**Quectel Pi M1/L1 typical application scenarios**

- After files are extracted or copied using **sudo**, their owner becomes **root**, preventing the regular user pi from editing them.

- If the permissions of a project directory copied from an external device do not match those of the current user, adjust them accordingly.

### chmod: manage access permissions

Use **chmod** when a file is readable but not writable, or when a script cannot be executed.

Basic syntax:

```plaintext
chmod [options] permissions file_or_directory
```

**Symbolic mode**

The format is as follows:

```plaintext
[ugoa][+-=][rwx]
```

Where:

- u represents the owner.

- g indicates the group.

- o means other users.

- a means all users.

Common examples:

Add execute permissions for the owner:

```plaintext
chmod u+x demo.sh
```

Add read permission for all users:

```plaintext
chmod a+r demo.txt
```

Remove write permissions for other users:

```plaintext
chmod o-w demo.txt
```

**Numeric mode**

Permissions can also be expressed in numerical form, for example:

```plaintext
chmod 755 demo.sh
chmod 644 notes.txt
```

The three digits correspond to:

```plaintext
chmod 754 demo.sh
    | | |
    | | +-- Other users (others) permissions
    | +---- Group (group) permissions
    +------ Owner (owner) permissions
```

Each rwx group consists of three permission bits: r, w, and x.

- Is r (read permission) enabled?

- Is w (write permission) enabled?

- Is x (execution permission) enabled?

These three permission bits can be represented either by additive values or as a three-bit binary number:

The corresponding relationship is as follows:

| **Permission bit** | **Binary bit** | **Decimal weight** |
| --- | --- | --- |
| r | 100 | 4 |
| w | 10 | 2 |
| x | 1 | 1 |

Therefore, the number of a set of permissions is essentially the sum of the weights of each enabled permission bit:

- r-- = 100 = 4

- rw- = 110 = 4 + 2 = 6

- r-x = 101 = 4 + 1 = 5

- rwx = 111 = 4 + 2 + 1 = 7

- --- = 000 = 0

## Example

**Add execution permissions to the script**

```plaintext
chmod u+x start.sh
./start.sh
```

**Protect private configuration files**

```plaintext
chmod 600 ~/.ssh/config
```

# File and directory management

Learn the most commonly used Linux file and directory commands: **pwd**, **cd**, **ls**, **mkdir**, **rmdir**, **cp**, **rm**, and **mv**, as well as file-viewing commands such as **cat** and **tail**.

In Linux, many routine operations involve paths and directories. Common file and directory commands are used to view logs, navigate project directories, copy model files, and remove unneeded resources.

## Basic concepts of paths and directories

### Current working directory

A terminal session always has a current working directory. Most commands work in the current directory by default, so it's important to know the location.

View the current directory:

```bash
pwd
```

### Path representation

- **Absolute path**: Start from the root directory /, such as */home/pi/project*.

- **Relative path**: Relative to the current directory, such as *project/src*.

Common special notations:

- .indicates the current directory.

- .. represents the parent directory.

- ~ represents the current user’s home directory, such as */home/pi*.

### Commonly used system directories

In **Debian**, users commonly work with the following directories:

| **Directory** | **Function** |
| --- | --- |
| */etc* | System configuration file. |
| */opt* | Third-party applications or custom programs. |
| */var/log* | System log. |
| */tmp* | Temporary files. |

### Common commands

#### ls: view directory contents

The **ls** command lists the files and subdirectories in a specified directory.

Example:

```bash
# View the contents of the current directory
ls

# View all files in the current directory, including hidden files
ls -la

# View more readable file sizes
ls -lh

# View files sorted by time
ls -ltr
```

#### cd: change directories

The **cd** command changes the current working directory to the specified path.

```bash
cd [dirName]
# dirName: target directory, which can be a relative path or an absolute path.
```

Example:

```bash
# Switch to the usr directory
cd /usr

#Return to the parent directory
cd ..

# Return to user home directory
cd ~

# Return to the previous working directory
cd -
```

#### mkdir and rmdir: create and delete directory

The **mkdir** command creates a directory, while **rmdir** removes an empty directory.

```bash
# -p ensures that the directory path exists, if it does not exist it will be created automatically
mkdir [-p] dirName

# -p If the parent directory becomes empty due to deletion of subdirectories, delete them together.
rmdir [-p] dirName
```

Example:

```bash
# Create a logs directory in the current directory
mkdir logs

# Automatically create non-existent parent directory project/data
mkdir -p project/data/raw

# Delete the logs directory, which must be empty
rmdir logs
```

#### cp: copy files and directories

Run the **cp** command to copy a file or directory from a source path to a destination path.

```bash
cp [options] source_file destination_file
```

Example:

```bash
#Copy the file source.txt to backup.txt
cp source.txt backup.txt

#copy directory
cp -r project project_backup
```

#### mv: move and rename

The **mv** command renames a file or directory, or moves it to another location.

```bash
# Move app.log to the /tmp/ directory
mv app.log /tmp/

# Rename the old_name.txt file to new_name.txt
mv old_name.txt new_name.txt

# Rename the directory, rename the dataset directory to dataset_old
mv dataset dataset_old
```

#### rm: delete file and directory

The **rm** command removes files or directories.

```bash
#Delete the file demo.txt
rm demo.txt

#Delete the demo_dir directory and subdirectories
rm -r demo_dir

#Force removal without prompting
rm -rf demo_dir
```

```{note}
**rm -rf** is a high-risk command, and deleted data cannot be recovered. Before running it, use **pwd** and **ls** to confirm the target path.
```

#### cat and tail: view file content

**cat**

The **cat** command concatenates files and writes their contents to standard output. It is commonly used to view file contents or combine multiple files.

```bash
#View the contents of the README.md file
cat README.md

#View with line number display
cat -n app.py
```

**tail**

The **tail** command displays the end of a file.

```bash
# The last 10 lines of system logs are displayed by default.
tail /var/log/syslog

# Check the last 50 lines of the system log /var/log/syslog
tail -n 50 /var/log/syslog

# Follow the log in real time
tail -f /var/log/syslog
```

## Basic operation examples

### Create and enter a project directory

```bash
mkdir -p ~/project/demo
cd ~/project/demo
pwd
```

### Back up configuration files

```bash
cp -i /etc/hosts ~/hosts.bak
```

### Clean up temporary directory

```bash
rm -r ~/project/demo/tmp
```

# Text editing

When developing with **Quectel Pi M1/L1**, you may need to modify configuration files, edit scripts, or adjust service parameters. Commonly used text editors in the terminal environment include **Vim** and **nano**. This section introduces both editors so that you can choose the one that best suits your needs.

## Vim editor

Vim is an enhanced version of the vi editor. It supports syntax highlighting, search and replace, batch editing, and other features. It is suitable for local terminals, serial terminals and SSH sessions.

If the system prompts that the command cannot be found, you can first execute the following command to install:

```bash
sudo apt update
sudo apt install vim
```

## Vim operating modes

According to common usage, Vim has three primary operating modes:

| **Mode** | **Function** | **How to enter** |
| --- | --- | --- |
| Command mode | Move cursor, copy, delete, save, exit | Enter by default after opening the file. |
| Input mode | Enter and modify text | Press **i**, **a**, **o** in command mode. |
| Command line mode | Execute commands such as save, exit, find and replace, etc. | Press **:** in command mode. |

The switching logic between these three modes is as follows:

- After opening a file, it enters command mode by default.

- When you need to input content, switch to input mode.

- Switch to command line mode when you need to save, exit, or perform a find and replace.

### Basic operations

1. **Open or create a file**

```bash
vim notes.txt
```

If the file does not exist, Vim will automatically create a new file.

2. **Enter input mode**

Press any of the following keys in command mode:

| **Key** | **Function** |
| --- | --- |
| **i** | Enter input mode at the current cursor position. |
| **a** | Enter input mode after the current cursor position. |
| **o** | Open a new line below the current line and enter input mode. |

3. **Text entry**

After entering input mode, you can enter characters like a normal editor.

4. **Return to command mode**

Press the **Esc** key to return to command mode.

5. **Save and exit**

In command mode, press **:** to enter command-line mode, and then enter and execute the appropriate command:

| **Command** | **Function** |
| --- | --- |
| **:w** | save |
| **:q** | Exit |
| **:wq** | Save and exit |
| **:q!** | Do not save, force quit |

### Common operating instructions

**Common instructions in command mode**

| **Key** | **Function** |
| --- | --- |
| **h j k l** | Move cursor left, down, up, right |
| **x** | Delete current character |
| **dd** | Delete the current line |
| **yy** | copy current line |
| **p** | Paste after the current line |
| **u** | Undo |
| **Ctrl+r** | Redo |
| **/keyword** | Search forward |
| **n** | Jump to next match |

**Common commands in command line mode**

| **Command** | **Function** |
| --- | --- |
| **:set nu** | Show line numbers |
| **:set nonu** | Hide line numbers |
| **:%s/old/new/g** | Replace all occurrences in the file |
| **:1,10s/old/new/g** | Replace lines 1 to 10 |

### Example

The following is an example of creating a simple script:

```bash
vim hello.sh
```

Press **i** to enter input mode, and then enter the following content:

```bash
#!/bin/bash
echo "Hello Quectel Pi"
```

Press **Esc** to return to command mode, then enter **:wq** to save and exit.

Then add execution permissions to the script:

```bash
chmod u+x hello.sh
./hello.sh
```

### Edit system files

To edit a file in a regular user's home directory, run:

```bash
vim ~/notes.txt
```

System configuration files typically require elevated privileges. Run Vim with sudo:

```bash
sudo vim /etc/hostname
```

It is recommended to back up the original file first:

```bash
sudo cp /etc/hostname /etc/hostname.bak
sudo vim /etc/hostname
```

### Troubleshooting common problems

**Unable to exit Vim**

Most of the time, you are still in input mode. Press the **Esc** key first, then enter **:q** or **:wq**.

**Permission denied when saving**

This indicates that the current file requires administrator privileges. Exit Vim, then reopen it using **sudo vim `<filename>`**.

**Chinese characters or indentation are displayed incorrectly**

These issues are usually related to terminal font or file encoding. Use UTF-8 encoding whenever possible, and ensure that the font used by the graphical terminal supports Chinese characters.

## nano editor

### Overview

nano is a lightweight terminal text editor with a simple and intuitive interface. It requires no mode switching, making it suitable for quickly editing configuration files and for users who are unfamiliar with Vim.

If nano is not installed, run the following commands:

```bash
sudo apt update
sudo apt install nano
```

### Basic operations

1. **Open or create a file**

```bash
nano notes.txt
```

If the file does not exist, nano will automatically create a new file. Once the file is opened, you can enter and edit text directly without switching modes.

2. **Edit text**

After opening the file, you can directly enter characters at the cursor position and use the arrow keys to move the cursor.

3. **Save file**

Press **Ctrl+O** (the letter O), nano will prompt to confirm the file name, press **Enter** key to confirm saving.

4. **Exit editor**

Press **Ctrl+X** to exit. If there are unsaved modifications to the file, nano will ask whether to save them:

- Press **Y** to save and exit.

- Press **N** to exit without saving.

- Press **Ctrl+C** to cancel the exit operation.

### Commonly used shortcut keys

nano displays common keyboard shortcuts at the bottom of the screen. The ^ symbol represents the Ctrl key.

| **Shortcut keys** | **Function** |
| --- | --- |
| **Ctrl+O** | Save file |
| **Ctrl+X** | Exit |
| **Ctrl+K** | Cut current line |
| **Ctrl+U** | Paste the cut content |
| **Ctrl+W** | Search text |
| **Ctrl+\** | Search and replace |
| **Ctrl+G** | View help |
| **Ctrl+C** | Show current cursor position |
| **Alt+U** | Undo |
| **Alt+E** | Redo |
| **Ctrl+A** | Move to beginning of line |
| **Ctrl+E** | Move to end of line |
| **Ctrl+Y** | Page up |
| **Ctrl+V** | Page down |

### Search and replace

**Search text**

Press **Ctrl+W**, enter the search term, and press **Enter** to jump to the first match. Press **Ctrl+W** and **Enter** again to jump to the next match.

**Search and replace**

Press **Ctrl+\**, enter the search string, and press **Enter**. Then enter the replacement string and press **Enter** again. The nano editor will prompt you to confirm each replacement:

- Press **Y** to replace the current match.

- Press **N** to skip the current match.

- Press **A** to replace all matches.

### Example

Take creating a simple script as an example:

```bash
nano hello.sh
```

Enter the following directly:

```bash
#!/bin/bash
echo "Hello Quectel Pi H1"
```

Press **Ctrl+O** to save, press **Enter** to confirm the filename, and then press **Ctrl+X** to exit.

Then add execution permissions to the script:

```bash
chmod u+x hello.sh
./hello.sh
```

### Edit system files

When editing system configuration files, you also need to use sudo permissions:

```bash
sudo nano /etc/hostname
```

# Software downloads and updates

On Debian, software is typically installed using APT or dpkg. Understanding their respective roles helps distinguish between installing packages from repositories and manually installing local .deb packages.

This section introduces the basic methods for installing and updating software on Debian, so that users can understand commands such as **apt install** when setting up their development environment.

For details about APT, common commands, and repository configuration, see [Software Update](<../../Operating System/Debian(Gnome)/Software Update/Software Update.md>).

## Overview of APT and dpkg

In Debian systems, software installation mainly relies on the following two types of tools:

| **Tools** | **Function** | **Typical scenario** |
| --- | --- | --- |
| **APT** | Find and download software from software sources and automatically handle dependencies | Install software and update system online. |
| **dpkg** | Install local .deb package directly | Manually install the installation package provided by the manufacturer. |

APT is a high-level package management tool that retrieves packages from repositories and resolves dependencies automatically. dpkg is a low-level tool used to install local .deb packages and does not resolve dependencies automatically.

## Common APT commands

## apt update

Update the package list. This command is used to refresh the local package index. This command does not install or upgrade any software, it is only used to update information about available software packages and their latest versions in the software repository.

Run the **apt update** command before installing software or upgrading the system.

```bash
sudo apt update
```

## apt upgrade

Upgrade installed software packages. This command will upgrade all installed software packages on the system to the latest version available in the software repository.

```bash
sudo apt upgrade
```

The usual procedure is to run **update** first, followed by **upgrade**:

```bash
sudo apt update
sudo apt upgrade
```

## apt install

The **apt install** command is the most commonly used command for installing packages. It retrieves the specified package from the configured repositories, installs it, and automatically resolves its dependencies.

```bash
sudo apt install package_name
```

When setting up a development environment, you will often use commands such as the following:

```bash
sudo apt install python3       # Install Python 3
sudo apt install git           # Install Git
sudo apt install vim           # Install Vim editor

#Multiple packages can be installed at once:
sudo apt install python3 git vim
```

## apt remove

The **apt remove** command removes the specified package from the system.

```bash
sudo apt remove package_name
```